%% @author Marc Worrell <marc@worrell.nl>
%% @copyright 2009-2025 Marc Worrell
%% @doc Interfaces for command line utilities in zotonic_launcher, some
%% easy shortcuts and error logging functions.
%% @end

%% Copyright 2009-2025 Marc Worrell
%%
%% Licensed under the Apache License, Version 2.0 (the "License");
%% you may not use this file except in compliance with the License.
%% You may obtain a copy of the License at
%%
%%     http://www.apache.org/licenses/LICENSE-2.0
%%
%% Unless required by applicable law or agreed to in writing, software
%% distributed under the License is distributed on an "AS IS" BASIS,
%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
%% See the License for the specific language governing permissions and
%% limitations under the License.

-module(z).
-author("Marc Worrell <marc@worrell.nl").

%% interface functions
-export([
    c/1,

    env/1,

    n/2,
    n1/2,
    m/0,
    compile/0,
    flush/0,
    restart/0,

    start/1,
    flush/1,
    restart/1,
    stop/1,

    open/1,
    open_secure/1,

    ld/0,
    ld/1,

    reindex/0,

    is_module_enabled/2,

    shell_stopsite/1,
    shell_startsite/1,
    shell_restartsite/1,

    dispatch_url/1,
    dispatch_path/2,
    dispatch_list/1,

    setconfig/3,

    debug_msg/2,

    log/3,

    debug/2,
    debug/3,
    debug/4,
    info/2,
    info/3,
    info/4,
    notice/2,
    notice/3,
    notice/4,
    warning/2,
    warning/3,
    warning/4,
    error/2,
    error/3,
    error/4,
    fatal/2,
    fatal/3,
    fatal/4
]).

-include("zotonic.hrl").

%% DTAP environment
-type environment() :: development
                    | test
                    | acceptance
                    | production
                    | education
                    | backup.

-type context() :: #context{}.
-type validation_error() :: invalid | novalue | {script, iodata()} | novalidator | string().
-type trans() :: #trans{}.
-type qvalue() :: binary() | string() | #upload{} | term().

-type severity() :: debug | info | notice | warning | error | fatal.

-export_type([
    context/0,
    trans/0,
    environment/0,
    validation_error/0,
    severity/0,
    qvalue/0
]).

% @doc Return a new context
-spec c( atom() ) -> z:context().
c(Site) ->
    z_context:new(Site).

%% @doc Return the current environment
-spec env( Site :: atom() ) -> environment().
env(Site) ->
    m_site:environment(Site).

%% @doc Send an async notification.
n(Msg, Site) when is_atom(Site) ->
    n(Msg, c(Site));
n(Msg, Context) ->
    z_notifier:notify(Msg, Context).

%% @doc Send a notification to the first observer and return the result.
n1(Msg, Site) when is_atom(Site) ->
    n1(Msg, c(Site));
n1(Msg, Context) ->
    z_notifier:first(Msg, Context).

%% @doc (Re)make all erlang source modules and reset the caches.
m() ->
    case compile() of
        ok -> flush(), ok;
        Other -> Other
    end.

%% @doc (Re)make all erlang source modules with the supplied compile
%% options. Do not reset the caches.
compile() ->
    zotonic_filehandler:compile_all().

%% @doc Reset all caches, reload the dispatch rules and rescan all modules.
-spec flush() -> ok.
flush() ->
    zotonic_fileindexer:flush(),
    [ flush(C) || C <- z_sites_manager:get_site_contexts() ],
    z_sites_dispatcher:update_dispatchinfo().

-spec flush( atom() | z:context() ) -> ok.
flush(Site) when is_atom(Site) ->
    flush(c(Site));
flush(Context) ->
    z_depcache:flush(Context),
    z_dispatcher:reload(Context),
    z_memo:flush(Context),
    n(module_ready, Context),
    ok.

%% @doc Reindex all sites, find new files.
reindex() ->
    zotonic_fileindexer:flush(),
    z_module_indexer:reindex().

%% @doc Check if a module of a site is enabled.
-spec is_module_enabled( Module :: atom(), Site :: atom() ) -> boolean().
is_module_enabled(Module, Site) ->
    z_module_manager:active(Module, c(Site)).

%% @doc Full restart of Zotonic
restart() ->
    application:stop(zotonic_core),
    application:start(zotonic_core).

%% @doc Start a site
start(Site) ->
    z_sites_manager:start(Site).

%% @doc Restart a site
restart(Site) ->
    z_sites_manager:restart(Site).

%% @doc Stop a site
stop(Site) ->
    z_sites_manager:stop(Site).

%% @doc Open a site in Chrome or the default browser(macOS)
open(Site) ->
    z_exec_browser:open(Site).

%% @doc Open a site in a new fresh Chrome
open_secure(Site) ->
    z_exec_browser:chrome(Site, [], #{ secure => true }).

%% @doc Reload all changed Erlang modules
ld() ->
    zotonic_filehandler:reload_modules().

%% @doc Reload an Erlang module
ld(Module) ->
    zotonic_filehandler:reload_module(Module).

%% @doc Shell commands: start a site
shell_startsite(Site) ->
    case z_sites_manager:get_site_status(Site) of
        {ok, running} ->
            running;
        {ok, _Status} ->
            z_sites_manager:start(Site);
        {error, bad_name} ->
            bad_name
    end.

%% @doc Shell commands: stop a site
shell_stopsite(Site) ->
    case z_sites_manager:get_site_status(Site) of
        {ok, stopped} ->
            stopped;
        {ok, _Status} ->
            z_sites_manager:stop(Site);
        {error, bad_name} ->
            bad_name
    end.

%% @doc Shell commands: stop a site
shell_restartsite(Site) ->
    z_sites_manager:stop(Site),
    shell_startsite(Site).

%% @doc Dispatch an URL - find matching site and dispatch the path
dispatch_url(Url) ->
    case uri_string:parse(Url) of
        #{ host := Host, path := Path } ->
            case z_sites_dispatcher:get_site_for_hostname(Host) of
                {ok, Site} ->
                    dispatch_path(Path, Site);
                undefined ->
                    case z_sites_dispatcher:get_fallback_site() of
                        {ok, FallbackSite} ->
                            dispatch_path(Path, FallbackSite);
                        undefined ->
                            {error, unknown_host}
                    end
            end;
        _ ->
            {error, url}
    end.

%% @doc Shell command: dispatch a path, return trace
dispatch_path(Path, Site) when is_atom(Site), is_binary(Path) ->
    case z_sites_manager:get_site_status(Site) of
        {ok, running} ->
            dispatch_path(Path, z_context:new(Site));
        {ok, Status} ->
            {error, Status};
        {error, bad_name} ->
            {error, bad_name}
    end;
dispatch_path(Path, #context{} = Context) when is_binary(Path) ->
    z_sites_dispatcher:dispatch_trace(Path, Context).

%% @doc Return the complete dispatch information for the site.
dispatch_list(SiteOrContext) ->
    case z_sites_dispatcher:fetch_dispatchinfo(SiteOrContext) of
        {ok, #site_dispatch_list{
                site=Site, hostname=Hostname, smtphost=SmtpHost, hostalias=Hostalias,
                redirect=Redirect, dispatch_list=DispatchList
            }} ->
            DL = lists:map(
                fun({Disp, Path, Controller, Opts}) ->
                    #{
                        dispatch => Disp,
                        path => Path,
                        controller => Controller,
                        controller_options => Opts
                    }
                end,
                DispatchList),
            {ok, #{
                site => Site,
                hostname => Hostname,
                smtphost => SmtpHost,
                hostalias => Hostalias,
                is_redirect => Redirect,
                dispatch_list => DL
            }};
        {error, _} = Error ->
            Error
    end.

%% @doc Set a runtime config value. This is useful to enable or disable certain
%% runtime features without restarting Zotonic.
setconfig(zotonic, Name, Value) when is_atom(Name) ->
    z_config:set(Name, Value).

%% @doc Echo and return a debugging value. This is useful for adding
%% debug anywhere in the code, as the passed argument is also returned.
%% Example: <tt>foo( ?DEBUG(Arg) )</tt> will add Arg as a notice to the logs
%% and still call  <tt>foo(Arg)</tt>.
debug_msg(Msg, Meta) ->
    logger:log(notice, "DEBUG: ~tp", [ Msg ], Meta),
    Msg.

%% @doc Log a debug message to the logs and the database, with extra meta data.
%% To add the current source location, use the <tt>?zDebug</tt> macro.
debug(Msg, Context)                 -> log(debug, Msg, #{}, Context).
debug(Msg, Meta, Context)           -> log(debug, Msg, Meta, Context).
debug(Format, Args, Meta, Context)  -> log(debug, Format, Args, Meta, Context).

%% @doc Log an informational message to the logs and the database, with extra meta data.
%% To add the current source location, use the <tt>?zInfo</tt> macro.
info(Msg, Context)                  -> log(info, Msg, #{}, Context).
info(Msg, Meta, Context)            -> log(info, Msg, Meta, Context).
info(Format, Args, Meta, Context)   -> log(info, Format, Args, Meta, Context).

%% @doc Log a  notice to the logs and the database, with extra meta data.
%% To add the current source location, use the <tt>?zNotice</tt> macro.
notice(Msg, Context)                -> log(notice, Msg, #{}, Context).
notice(Msg, Meta, Context)          -> log(notice, Msg, Meta, Context).
notice(Format, Args, Meta, Context) -> log(notice, Format, Args, Meta, Context).

%% @doc Log a warning to the logs and the database, with extra meta data.
%% To add the current source location, use the <tt>?zWarning</tt> macro.
warning(Msg, Context)              -> log(warning, Msg, #{}, Context).
warning(Msg, Meta, Context)        -> log(warning, Msg, Meta, Context).
warning(Format, Args, Meta, Context)->log(warning, Format, Args, Meta, Context).

%% @doc Log a error to the logs and the database, with extra meta data.
%% To add the current source location, use the <tt>?zError</tt> macro.
error(Msg, Context)                -> log(error, Msg, #{}, Context).
error(Msg, Meta, Context)          -> log(error, Msg, Meta, Context).
error(Format, Args, Meta, Context) -> log(error, Format, Args, Meta, Context).

%% @doc Log a fatal error to the logs and the database, with extra meta data.
%% To add the current source location, use the <tt>?zError</tt> macro.
fatal(Msg, Context)                -> log(fatal, Msg, #{}, Context).
fatal(Msg, Meta, Context)          -> log(fatal, Msg, Meta, Context).
fatal(Format, Args, Meta, Context) -> log(fatal, Format, Args, Meta, Context).


-spec log( Level::severity(), Format::string(), Args::list(),
           Meta::proplists:proplist() | map(), Context::z:context() ) -> ok.
log(Type, Format, Args, Meta, Context) when is_list(Args) ->
    Msg1 = lists:flatten(io_lib:format(Format, Args)),
    log(Type, Msg1, Meta, Context).

-spec log( Level::severity(), Meta::proplists:proplist() | map(), Context::z:context() ) -> ok.
log(Type, Meta, Context) ->
    log(Type, <<>>, Meta, Context).

-spec log( Level::severity(), Msg::iodata(), Meta::proplists:proplist() | map(), Context::z:context() ) -> ok.
log(Type, Msg, Meta, Context) when is_list(Meta) ->
    log(Type, Msg, maps:from_list(Meta), Context);
log(Type, Msg, Meta, Context) ->
    Line = maps:get(line, Meta, 0),
    UserId = case maps:get(user_id, Meta, none) of
        none -> z_acl:user(Context);
        UId -> UId
    end,
    LoggerMeta = #{
        site => z_context:site(Context),
        environment => m_site:environment(Context),
        line => Line,
        node => node(),
        user_id => UserId
    },
    LoggerMeta1 = case maps:get(mfa, Meta, undefined) of
        undefined ->
            LoggerMeta;
        {_, _, _} = MFA ->
            LoggerMeta#{ mfa => MFA }
    end,
    LoggerMeta2 = maps:merge(Meta, LoggerMeta1),
    Msg1 = unicode:characters_to_list(Msg),
    case Msg1 of
        "" -> logger:log(logger_level(Type), LoggerMeta2);
        _ -> logger:log(logger_level(Type), Msg1, LoggerMeta2)
    end,
    z_notifier:notify(
        #zlog{
            type = Type,
            user_id = UserId,
            timestamp = os:timestamp(),
            props = #log_message{
                type = Type,
                message = Msg1,
                props = maps:to_list(Meta),
                user_id = UserId
            }
        },
        Context),
    ok.

logger_level(fatal) -> alert;
logger_level(error) -> error;
logger_level(warning) -> warning;
logger_level(notice) -> notice;
logger_level(info) -> info;
logger_level(debug) -> debug.
